/*-------------------------------------------------------------------------
 *
 * relptr.h
 *	  该文件包含相对指针的基本声明。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/relptr.h
 *
 *-------------------------------------------------------------------------
 */

#ifndef RELPTR_H
#define RELPTR_H

/*
 * 相对指针旨在用于存储一个可能相对于
 * 进程地址空间的基址或映射在其中的某个动态共享内存段的地址。
 *
 * 这里的想法是你声明一个相对指针为 relptr(type)
 * 然后使用 relptr_access 解引用它，使用 relptr_store 更改
 * 它。这里使用联合体是一种变通方法，因为存储在
 * relptr 中的始终是一个 Size，而不是实际指针。
 * 但是在联合体中包含一个指针使我们能够使用某些愚蠢的宏技巧
 * 来提供一定程度的类型安全性。
 */
#define relptr(type)	 union { type *relptr_type; Size relptr_off; }

/*
 * pgindent 对直接使用"relptr(type)"的声明感到困惑，
 * 因此首选的风格是编写
 *		typedef struct ... SomeStruct;
 *		relptr_declare(SomeStruct, RelptrSomeStruct);
 * 然后声明指针变量为 "RelptrSomeStruct someptr"。
 */
#define relptr_declare(type, relptrtype) \
	typedef relptr(type) relptrtype

#ifdef HAVE__BUILTIN_TYPES_COMPATIBLE_P
#define relptr_access(base, rp) \
	(AssertVariableIsOfTypeMacro(base, char *), \
	 (__typeof__((rp).relptr_type)) ((rp).relptr_off == 0 ? NULL : \
		(base) + (rp).relptr_off - 1))
#else
/*
 * 如果我们没有 __builtin_types_compatible_p，假设我们也可能没有
 * __typeof__。
 */
#define relptr_access(base, rp) \
	(AssertVariableIsOfTypeMacro(base, char *), \
	 (void *) ((rp).relptr_off == 0 ? NULL : (base) + (rp).relptr_off - 1))
#endif

#define relptr_is_null(rp) \
	((rp).relptr_off == 0)

#define relptr_offset(rp) \
	((rp).relptr_off - 1)

/* 我们使用这个内联来避免在 relptr_store 中重复评估 "val" */
static inline Size
relptr_store_eval(char *base, char *val)
{
	if (val == NULL)
		return 0;
	else
	{
		Assert(val >= base);
		return val - base + 1;
	}
}

#ifdef HAVE__BUILTIN_TYPES_COMPATIBLE_P
#define relptr_store(base, rp, val) \
	(AssertVariableIsOfTypeMacro(base, char *), \
	 AssertVariableIsOfTypeMacro(val, __typeof__((rp).relptr_type)), \
	 (rp).relptr_off = relptr_store_eval((base), (char *) (val)))
#else
/*
 * 如果我们没有 __builtin_types_compatible_p，假设我们也可能没有
 * __typeof__。
 */
#define relptr_store(base, rp, val) \
	(AssertVariableIsOfTypeMacro(base, char *), \
	 (rp).relptr_off = relptr_store_eval((base), (char *) (val)))
#endif

#define relptr_copy(rp1, rp2) \
	((rp1).relptr_off = (rp2).relptr_off)

#endif							/* RELPTR_H */
